Create a series of promo codes

The request is used to create a request to issue a new series of promo codes.

Request syntax

POST https://b2b-api.go.yandex.ru/integration/2.0/promocodes/orders/create

Request headers

Authorization: Bearer <OAuth-token>
OAuth access token. The steps to get a token are described in Getting started.

X-YaTaxi-Selected-Corp-Client-Id — client ID from the account. Required if multiple clients are available using the token.

X-Idempotency-Token — idempotency token, a string using UUID format. One idempotency token corresponds to one order; a new order requires generating a new token. Required header.

Request body

The data about a new order of promo codes is passed in the request body in JSON format:

Field	Description	Format	Required
`name`	Order name.	String	No
`max_usages_count`	Maximum number of rides per promo code from the series. The default is 1.	Number	No
`value`	Value of a single promo code.	Number	Yes
`count`	Number of promo codes.	Number	Yes
`service`	The service promo codes are created for. Possible values: `taxi` `grocery` `eats` `fuel` `cargo` The default is `taxi`.	String	No
`classes`	The list of service classes covered by a taxi promo code. No restrictions are set by default.	Array of strings	No
`active_from`	Promo code start date in `YYYY-MM-DD` format. The default is the request date.	String	No
`active_until`	Promo code expiration date in `YYYY-MM-DD` format.	String	Yes
`bin_ranges`	An array of BIN code ranges where each element is a pair of start and end values.	Array	No
`bank_name`	Bank name dictionary in JSON format with language codes as keys and bank names as values.	Object	No
`geo_restrictions`	List of geo restrictions. You can limit the distance to pickup location and the distance to destination. The restrictions from the list are combined by the `OR` condition.	Array of objects	No

Structure of the geo_restrictions array element:

Field	Description	Format
`source`	ID of the region where ride can be started.	Object
`destination`	ID of the region where ride can be ended.	Object
`max_intermediate_points`	The maximum number of intermediate points in a ride. The default is 0.	Number

Either the source or destination field must be specified in the geo_restrictions array.

For more information about creating new regions, see Create a new region.

Structure of the source and destination objects:

Field	Description	Format
`geo_restriction_id`	Region ID.	String

Restrictions and their values:

Restriction	Taxi	Fuel, Cargo	Lavka, Eats
`service`	"taxi"	"fuel", "cargo"	"grocery", "eats"
`value`	Maximum: 5000 Minimum: 100	Maximum: 5000 Minimum: 100	Maximum: 30,000 Minimum: 100
`count`	Maximum: 1000 Minimum: 5	Maximum: 1000 Minimum: 5	Maximum: 1000 Minimum: 5
`active_until`	No more than 90 days. The count starts from the date of the promo code creation request.
`max_usages_count`	Maximum: 20 Minimum: 1	Maximum: 20 Minimum: 1	Maximum: 20 Minimum: 1
`name`	Maximum: 256 Minimum: 1	Maximum: 256 Minimum: 1	Maximum: 256 Minimum: 1
`geo_restrictions`	Available only for Taxi.	—	—
`classes`	Available only for Taxi.	—	—

Class	Pricing plan
Economy	`econom`
Comfort	`business`
Comfort+	`comfortplus`
Minivan	`minivan`
Kids	`child_tariff`
Business	`vip`
Premier	`ultimate`
Élite	`maybach`
Cruise	`premium_van`
Bike courier	`courier_walking`
Express	`express`
Cargo	`cargo`
Cargo by the hour	`cargo_hour`

Response field description

The response may contain the following fields:

Field	Description	Format
`id`	The promo code order ID number.	String

Request example

POST https://b2b-api.go.yandex.ru/integration/2.0/promocodes/orders/create
...
Authorization: Bearer <OAuth-token>
X-YaTaxi-Selected-Corp-Client-Id: <client-id>
X-Idempotency-Token: <token>

{
  "name": "New order",
  "max_usages_count": 2,
  "value": 220,
  "count": 31,
  "service": "taxi",
  "classes": ["econom"],
  "active_from": "2024-11-22",
  "active_until": "2024-12-01",
  "bin_ranges": [
    ["123400", "123499"],
    ["555000", "555123"]
  ],
  "bank_name": { 
    "ru": "Банк", 
    "en": "The Bank" 
  },  
  "geo_restrictions": [
    {
        "max_intermediate_points": 2,
        "source": {
          "geo_restriction_id": "be9...d4a"
        },
        "destination": { 
          "geo_restriction_id": "be9...d4a"
        }
    }
  ]
}

Response example

{
  "order_id": "15с...83d"
}

Response codes

The response to this request can contain the following standard HTTP codes:

200: Request completed successfully.
400: An unknown parameter or a parameter with an invalid value was passed in the request.
403:
- SELECT_CLIENT_HEADER_REQUIRED: the request did not pass the header X-YaTaxi-Selected-Corp-Client-Id (returned if more than one client is available for the token).
- SELECTED_CLIENT_ACCESS_DENIED: the header X-YaTaxi-Selected-Corp-Client-Id contains the client's ID, which this login does not have access to.

Was the article helpful?

Remove region

Cancel an order of promo codes